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PREFACE 

The Ethernet System Product Line (ESPL) Software Reference Manual 
provides the Bridge Communications customer with the information 
necessary to add software to a Bridge ESPL product. 

The publication was prepared based on the following assumptions 
of reader knowledge: 

1. The reader should be familiar with the information provided 
in the Bridge Communications Ethernet System Product Line 
Overview and CS/1 User's Guide . 

2. The reader should be familiar with the Ethernet Specifica¬ 
tion, Version 1.0 (see reference [4]). 

3. The reader should be familiar with the Xerox Network System 

high-level protocols (see references [5], [6] and [7]). 

4. The reader should have some familiarity with the UNIX* 
operating system (see reference [8]). 

5. The reader should be familiar with the "C" language (see 
reference [9]), or other high-level structured languages. 

6. The reader should be familiar with the material presented in 
Volume One of this manual (particularly Section 5.0, the 
Kernel Interface). 

Volume Three of the Software Technical Reference Manual is 
grouped in three major sections whose contents are as follows: 

Section 1.0 - Introduction: Provides an overview of the three 

volumes of the Software Technical Reference Manual 
and describes their purpose and scope. 

Section 2.0 - Data Link Service: Describes the Data Link Ser¬ 
vice, which provides a means of sending packets 
compatible with the Ethernet Version 1.0 Specifi¬ 
cation. The interfaces with higher-level protocol 
layers are defined. 

Section 3.0 - Serial I/O Interface: Describes the Serial I/O 

(SIO) interface between the serial I/O driver and 
software on the Main CPU board. 

Volume One of this manual describes the ESPL software architec¬ 
ture, development environment, MCPU monitor, operating system and 
floppy disk interface. Volume Two describes the high-level pro¬ 
tocols used in the ESPL. 



*UNIX is a Trademark of Bell Laboratories. 




Bridge Communications, Inc. 


09-0018-00 




ESPL Software Technical Reference Manual 


Volume Three 


REFERENCES 

The following publications describe the Bridge Communications 
Ethernet System Product Line (ESPL) : 

[1] Ethernet System Product Line Overview , 

Bridge Communications, Inc. 

[2] ESPL Communications Server/1 User 1 s Guide , Bridge Communica¬ 
tions, Inc. 

[3] ESPL Software Reference Manual , Volumes One and Two , Bridge 
Communications, Inc. 


The following publications describe Ethernet and the Xerox Net¬ 
work System products: 

[4] The Ethernet , A Local Area Network ; 

Data Link Layer and Physical Layer Specifications , Version 
1.0 (Digital Equipment Corporation, Intel Corporation, and 
Xerox Corporation, 1980) 

[5] Internet Transport Protocols , XSIS 028112 (Xerox Corpora¬ 
tion, 1981) 

[6] Courier : The Remote Procedure Call Protocol , XSIS 038112 
(Xerox Corporation, 1981) 

[7] D. Oppen, Y. Dalai, The Clearinghouse : A Decentralized Agent 
for Locating Named Objects in a Distributed Environment 
(Xerox Corporation, 1981) 


The following publications describe other related specifications: 


[8] 

UNIX Programmer's Manual, Seventh Edition, 
Version, (University of California, Berkeley 

Virtual 
, 1981) 

VAX-11 

[9] 

B. Kernighan, D. Ritchie, The C Programming 
tice Hall, Inc., 1978) 

Language 

(Pren- 

[10] 

MC68000 Microprocessor User's Manual, 

MC68000UM(AD3) (Motorola Corporation, 1982) 

Second 

Edition 

[11] 

MC68000 Educational Computer Board User's 
Edition MEX68KECB/D2 (Motorola Corporation, 

Manual, 
1982) 

Second 


09-0018-00 


Bridge Communications, Inc. 


nr 



Volume Three 


ESPL Software Technical Reference Manual 


TABLE OF CONTENTS 


1.0 INTRODUCTION.1-1 

2.0 DATA LINK SERVICE..2-1 

2.1 Overview.2-1 

2.1.1 ESB Firmware and Software.2-1 

2.1.2 ESB Hardware.. . 2-1 

2.1.3 ESB Control Structure.2-2 

2.1.4 Initialization.2-3 

2.1.6 Transmission.2-4 

2.1.6 Reception.2-5 

2.2 Communication Between Firmware and Agent .... 2-6 

2.2.1 Control Commands .2-7 

2.2.2 Block Commands.2-8 

2.2.3 Data Structures.2-8 

2.2.3.1 System Control Block . 2-10 

2.2.3.2 Command Block List ....... 2-11 

2.2.3.3 Receive Packet Area . 2-13 

2.2.3.4 Packet Descriptor.2-13 

2.2.3.5 Buffer Descriptor . 2-14 

2.2.3.6 Network Table . 2-15 

2.3 Client Interface to ESB Agent.2-16 

2.3.1 Eainit Procedure Call.2-16 

2.3.2 EaU2Nxmit Procedure Call.2-17 

2.3.3 ML0RCV Message.2-18 

2.3.4 Receiver Restart Message . 2-18 

2.4 Peer Protocol.2-19 

3.0 SERIAL I/O SERVICE.3-1 

3.1 Overview.3-1 

3.1.1 SIO Software.3-1 

3.1.2 SIO Hardware.3-2 

3.1.3 Agent/Firmware Control Structure .... 3-3 

3.1.4 Initialization.3-4 

3.1.5 Line Configuration.. 3-4 

3.1.6 Transmission.3-5 

3.1.7 Reception.3-5 

3.2 Communication Between Firmware and Agent .... 3-5 

3.2.1 Channel Attention . 3-5 

3.2.2 Multibus Interrupt . 3-6 

3.2.3 SIO Reset.3-6 

3.2.4 Software Control Flags . 3-7 

3.2.5 Commands.3-7 

3.2.6 Synchronization.3-8 

3.2.7 Data Structures.3-9 

3.2.7.1 SIO Control Block . 3-11 

3.2.7.2 Command Block . 3-13 

3.2.7.3 Agent Private Data Structures . 3-14 





i v 


Bridge Communications, Inc. 


09-0018-00 













































ESPL Software Technical Reference Manual 


Volume Three 


3.3 Client Interface to SIO Agent.3-15 

3.3.1 Connect Request Procedure Call 

and Message.3-15 

3.3.2 Disconnect Request Procedure Call 

and Message.3-16 

3.3.3 Connected Procedure Call.3-17 

3.3.4 Disconnected Procedure Call and Message . 3-17 

3.3.5 Board Initialization Procedure Call . . . 3-18 

3.3.6 Set Parameters Procedure Call.3-18 

3.3.7 Change Parameter Procedure Call . 3-19 

3.3.8 Flow Control Procedure Call.3-20 

3.3.9 Restart Line Procedure Call and Message . 3-20 

3.3.10 Send Data Procedure Call.3-21 

3.3.11 Receive Data Message . 3-22 

3.3.12 Send Attention Procedure Call . 3-22 

3.3.13 Full CBL Message . ..... 3-23 


Bridge Communications, Inc. 


09-0018-00 


v 











Volume Three 


ESPL Software Technical Reference Manual 


LIST OF TABLES 



No. Title Page 


2- 1 Receiver Restart Algorithm . 2-19 

3- 1 SIO Line Number/Port Mapping.3-2 

3-2 SIO Channel Attention, Multibus Interrupt and 

Reset Addresses.3-6 


LIST OF FIGURES 


No. Title Page 


2-1 ESB Command and Message Flow.. 2-7 

2- 2 ESB Control Structure .2-9 

3- 1 SIO Synchronization Control . 3-8 

3-2 SIO Data Structures.3-10 




c 


vi 


Bridge Communications, Inc 


09-0018-00 










ESPL Software Technical Reference Manual 


Volume Three 


1.0 INTRODUCTION 

The ESPL Software Reference Manual provides the Bridge Communica¬ 
tions OEM-level customer with the information necessary to add 
software to an Ethernet System Product Line product. In addi¬ 
tion, it provides information about the existing ESPL software 
modules for the sophisticated user (e.g., the Network Manager). 

The manual makes no attempt to present tutorial-level material 
aimed at the end user; please refer to the appropriate User's 
Guide for tutorial material. 

The Software Technical Reference Manual is divided into three 
volumes. Volume One describes the ESPL overall software archi¬ 
tecture, the software development environment, the kernel and 
various support software. Volume Two describes the high-level, 
packet-processing protocols used in the ESPL. Volume Three (this 
manual) describes the ESPL drivers and firmware. 
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2.0 DATA LINK SERVICE 

This section describes the Data Link Service. Section 2.1 pro¬ 
vides an overview of the service and the functions it performs, 
and Section 2.2 describes the interface between the Data Link 
firmware (residing on the ESB board) and its agent (residing on 
the MCPU board). Section 2.3 describes the interfaces between 
the Data Link Service and its level one client protocols. Sec¬ 
tion 2.4 indicates the Ethernet peer protocols with which the 
Data Link Service communicates. 

2.1 Overview 

The data link layer is the lowest layer of protocol in the net¬ 
work. Its primary functions are transmitting and receiving pack¬ 
ets, keeping statistics about network traffic, packet charac¬ 
teristics and errors, and supporting diagnostic aids (including 
power-on diagnostics and higher-level testing). The majority of 
the data link protocol resides as firmware on the Ethernet Shared 
Buffer (ESB) board. This firmware is known as the ESB firmware. 
In addition, an ESB Agent (EA) module residing on the MCPU acts 
as a driver for the Ethernet controller, and provides an inter¬ 
face to the data link layer for IDP or any other client layer. 

2.1.1 ESB Firmware and Software 

There are two operational units of the ESB firmware: the Command 
Unit (CU) and the Receive Unit (RU). The natural division into 
the two units is synchronous versus asynchronous. The CU handles 
the communication with the ESB agent, performs any control com¬ 
mands, and initiates any transmit requests. The RU handles packet 
reception from the Ethernet, providing separation of the data 
link header from the data portion of the packet. The RU performs 
data chaining on transmit as well as receive. 

2.1.2 ESB Hardware 

The FIFO register structure of the ESB DMA provides the capabil¬ 
ity to scatter-write during packet reception. This is exploited 
so that the header information can be placed in a separate loca¬ 
tion from the data. The data portion of the packet could be 
received into discontiguous memory segments, though it is typi¬ 
cally received into a single contiguous block. The reception of 
back-to-back packets, however, is made possible with the FIFO 
register and scatter-write capability. Address filtering is per¬ 
formed by the Ethernet Transceiver Interface (ETI) hardware, 
unless the multicast bit in the address is set; all multicast 
filtering is done by the ESB firmware. The ESB may be set to 
receive promiscuously. 
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2.1.3 ESB Control Structure 

Commands and buffers are passed to the ESB firmware from the ESB 
Agent (EA) via the control structure called the System Control 
Block (SCB). The SCB contains pointers to lists of buffers and 
commands, as well as fields for error statistics (CRC, alignment, 
and resource errors). The EA presents new commands to the ESB 
firmware by acquiring a command block in the Command Block List 
(CBL), formatting it and logically chaining it to the end of the 
CBL. The free buffer pool is expanded by appending new buffers 
onto the end of the buffer list. Some commands are written 
directly into the SCB (control commands only, with no parameters 
or data associated with them). 

The packets received with CRC or alignment errors are counted by 
the ESB agent, and then discarded. Resource errors occur when 
there are not enough buffers for packet reception. If this hap¬ 
pens, the receiver shuts down and must be restarted by the agent 
when the supply of buffers increases again. 

In addition, the ESB firmware keeps a count of the following 
statistics for use by Network Management: 

1. Packets too short (Receive) 

2. Packets too long (Receive) 

3. Number of collisions (Transmit) 

4. Packet size histogram (Receive and Transmit) 

5. Retransmission histogram (Transmit) 

6. Number of packets with CRC errors (Receive) 

7. Number of resource errors (Receive) 
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2.1.4 Initialization 


The ESB agent is started up by a client process (usually the IDP 
process) via the "eainit" procedure call described in Section 
2.3.1. IDP obtains the required information from its Service 
Access Point Table, which contains an entry for every attached 
network (i.e., each agent with which IDP must be able to communi¬ 
cate) including the entry point for initialization. The table is 
described in more detail in Volume Two, Section 2.0. 
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tern Control 
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It is extremely important that the two proce 
in the initialization effort. The order is a 
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While the firmware waits, the agent initializes the SCP, SCB, 
RPA, and CBL to a ready state and then sends a Channel Attention 
to the ESB firmware. On receipt of the first Channel Attention, 
the ESB firmware reads the SCP from the known location, finds the 
SCB, and starts executing commands from the Command Block List 
(CBL) . 


The ESB addresses are in Multibus memory relative to the MCPU. As 
the MCPU views this memory, the ESB resides in a single 256K-byte 
block which is one of four 256K-byte block partitions of the 
address range from 1M to 2M. However, the ESB CPU only decodes 
the low 17 bits of the offset into Multibus memory, so to the ESB 
each 128K-byte block in the 1M to 2M range is identical to any 
other. 

From the MCPU point of view, the low 128K bytes of each 256K-byte 
block are in a straight access window, while the high 128K bytes 
are in a swapped access window (refer to Volume One, Section 
5.1.5, for a description of the straight and swapped access win¬ 
dows). In a system containing two ESBs (e.g., an Ethernet-to- 
Ethernet bridge), from the MCPU's viewpoint ESB1 would have the 
range 100000-13FFFF, while ESB2 would have 140000-17FFFF. 
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The agent would initialize ESB1 by writing to 11FF1C and giving 

it a Channel Attention with a write to 11FFE0, and initialize 

ESB2 by writing to 15FF1C and giving it a Channel Attention with 
a write to 15FFE0. Each ESB, however, would look at 11FF1C (or 
15FF1C, 19FF1C, 1DFF1C, depending on its ESB number) on receipt 
of the first Channel Attention to find its SCP and SCB. 

The following steps summarize the initialization process: 

1. The ESB firmware initializes variables and devices, and 

waits for the first Channel Attention from the agent. 

2. The ESB agent sets up the ESB interrupt handler with the 

kernel and initializes state variables. 

3. The ESB agent initializes the SCP (located at 11FF1C for 
ESB1, and at 15FF1C for ESB2), SCB, CBL and RPA, and issues 
the ESB firmware its first Channel Attention by writing to 
11FFE0 (for ESB1) or 15FFE0 (for ESB2). 

4. The ESB firmware reads the SCP, finds the SCB, performs any 
control commands in the SCB and possibly starts executing 
commands in the CBL. 


2.1.5 Transmission 

The data link layer transmits all packets destined for another 
station on the network. It must obey the rules of the contention 
scheme, and must present the data to the physical layer in a con¬ 
tiguous stream of bytes once access to the channel is acquired. 

Some of the transmit functions are provided by the hardware and 
some by the software. The transmit functions provided by the 
hardware include generating the preamble to the packet, serializ¬ 
ing the sequence of octets into a stream of bits, generating the 
CRC and appending it to the end of the packet, performing Man¬ 
chester encoding on the bit stream, deferring, enforcing the 
interpacket gap, detecting collisions, and reinforcing collisions 
with jamming. 

The functions performed by the ESB software during transmission 
include padding packet to minimum length, initiating transmission 
of a packet (data link header and data portion), keeping track of 
the number of retries, performing the truncated binary exponen¬ 
tial backoff algorithm, and recording transmission errors. 
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Address recognition and carrier sense are hardware functions. 
The firmware Receive Unit is activated after a successful address 
match on an incoming packet (i.e., the destination address 
matches the host address). If the multicast bit in the destina¬ 
tion address of the data link header is set, the packet will be 
received and the multicast addresses will be filtered by the 
firmware. True broadcast packets are always received. 


The ESB agent is responsible for maintaining a pool of free 
buffers into which packets may be received, and for feeding the 
characteristics of these buffers to the FIFO register as needed 
by the DMA to continue reception of the incoming bit stream. The 
ESB firmware feeds the buffer addresses to the FIFO register, and 
records the count at the end of a packet full of data. 


The ESB agent keeps the buffer pool well-stocked, replacing 
buffers as they are used up, and maintaining a reasonable margin 
of the number of buffers available at one time. The goal is to 
never run out of buffers if at all possible, without absorbing 
system resources in the process. This might not always be possi¬ 
ble if traffic is very heavy; buffers may not be available at the 
time of the interrupt, and the firmware might need to stop 
receiving until there are more buffers. A process known as Data 
Link Network Manager (DLNM) assists the ESB agent in situations 
such as this. When the firmware reports to the agent (via the 
SCB field "esb_stat") that it has stopped receiving due to a 
shortage of buffers or packet descriptors, the interrupt routine 
tries to restock the pool and sends a message to DLNM to restart 
the receiver. DLNM then checks the buffer pool, replenishes it 
if necessary, and issues a control command (via the SCB field 
"esb cmd") to resume the receive unit. 
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2.2 Communication Between Firmware and Agent 

The ESB agent runs on behalf of the level one internetwork layer 
protocol (IDP or a customer's network layer protocol) and pro¬ 
vides an interface to the ESB that is based partly on procedure 
calls (synchronous) and partly on messages from interrupt level 
(asynchronous). 

There are three singly-linked lists the agent stocks: the PD 
list, the BD list, and the CBL list. The PD list is of finite 
length; the elements in the list are allocated once during ini¬ 
tialization, but never given back to free storage. Instead, their 
contents (Ethernet header and pointer to first buffer descriptor) 
are copied into a message block and passed to the appropriate 
recipient. The PDs are always linked circularly, with the head 
being pointed to by the SCB and by another pointer held by the 
agent, and the tail pointed to by a status bit in the PD itself 
and by another pointer held by the agent. If the ESB firmware 
runs out of PDs, a resource error is noted in the statistics 
block of the SCB. 

The BDs are allocated at initialization and every time a packet 
is successfully received by the ESB agent. The method for replen¬ 
ishing the ESB buffer pool is to allocate as many new buffers as 
are used each time a packet is received. There is no re-use of 
transmit buffers; they are freed when transmission terminates 
(whether successfully or not). If the ESB runs out of buffers, a 
resource error is noted in the statistics block of the SCB. 

At any time, the statistics that the ESB firmware is keeping on 
the network traffic can be read by the Statistics Monitor, so no 
special communication between processors is necessary. 

There are two types of commands to which the ESB firmware 
responds: control commands (resume, suspend, reset, acknowledge¬ 
ments) and block commands (transmit packet, read host address 
from prom, add multicast address for receive). The ESB firmware 
can report asynchronous events to the ESB agent via the status 
fields in the SCB and an interrupt line. 

Figure 2-1 illustrates the flow of commands and messages between 
the ESB firmware, the ESB agent, and the agent's client 
processes. 
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Figure 2-1 Command and Message Flow 


2.2.1 Control Commands 


Control commands are communicated to the ESB firmware via the 
SCB. They have no parameters. The ESB agent writes the command 
into the command field in the SCB and issues a Channel Attention 
to the ESB firmware. The ESB firmware acknowledges completion of 
any of these commands by writing a zero into the same field. Two 
commands (resume and suspend) apply individually to either unit. 
In addition, the reset command always applies simultaneously to 
both units. 

The command field in the SCB is also used by the ESB agent to 
acknowledge the following ESB events: 


1. 

Command 

completed. 


2. 

Packet 

received. 


3. 

Command 

Unit becoming not 

ready. 

4. 

Receive 

Unit becoming not 

ready. 


Refer to Section 2.2.3.1 for the specific bit values used to 
specify commands and acknowledge events. 
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2.2.2 Block Commands 

The block commands are chained together in shared memory, and the 
SCB contains a pointer to the first command in the chain. Each 
command is composed of two parts: the common portion with the 
standardized status, link, and command name fields; and the com¬ 
mand specific portion, which is different for each command. 



2.2.3 Data Structures 

The data structures used by the ESB firmware and agent reside in 
shared ESB memory. Interprocessor communication is conducted via 
these structures (plus a Channel Attention or a Multibus inter¬ 
rupt, depending on the direction of information flow). The data 
structures include the System Control Block (SCB), the Command 
Block List (CBL), the Receive Packet Area (RPA), the Packet 
Descriptor (PD), the Buffer Descriptor (BD), respectively. In 
addition, the agent maintains in private memory a data structure 
called the NET table, which contains pointers into the shared 
data structures. These data structures are illustrated in Figure 
2-2, and described in the subsequent subsections. 


|v. ■ ] 
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Shared Memory 



Figure 2-2 ESB Control Structure 
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2.2.3.1 System Control Block 

The "C” representation of the SCB data structure is as follows: 

#define SCB struct scb /* definition of SCB */ 

SCB { 


short 

esb_ 

stat ; 

/* 

status of ESB RU and CU 





* 

* 

bits 

meaning 





* 

9-15 

unused 





* 

8 

reset 





* 

7 

completed CBL command 





* 

6 

packet received 





* 

5 

CU not ready 





* 

4 

RU not ready 





* 

3 

CU Ready/Not Ready 





* 

2 

RU Ready/Not Ready 





* 

"k 

1-0 

unused 





* 

bits 

4-7 are valid only at the 





* 

* 

time 

/ 

of interrupt to agent 


short 

esb 

cmd; 

/*' 

f 

command field, set by agent. 





* 

cleared by ESB CPU 





* 

bi ts 

meaning 





* 

8-15 

unused 





* 

7 

ack command executed 





* 

6 

ack packet received 





* 

5 

ack CU not ready 





* 

4 

ack RU not ready 





* 

3 

suspend CU 





* 

2 

resume CU 





* 

1 

suspend RU 





* 

0 

resume RU 





* 

/ 



CB 

*esb_cbl; 

/*' 

ptr 

to command block list 

*/ 

PD 

*esb rpa; 

/* 

ptr 

to receive packet area 

*/ 

short 

esb 

PktPend; 

/* 

no. 

of processed packets (valid 






at time of intrpt to MCPU) 

*/ 

short 

esb_ 

CmdCmplt 

; / 

* no. 

of cmds completed (valid 






at time of intrpt to MCPU) 

*/ 

long 

esb_ 

_crc; 

/* 

no. 

crc err since powerup 

*/ 

long 

esb 

algn; 

/* 

no. 

align, err since p.u. 

*/ 

long 

esb_ 

pderr; 

/* 

no. 

PD rsrc err since p.u. 

*/ 

long 

esb_ 

bderr; 

/* 

no. 

BD rsrc err since p.u. 

*/ 

long 

esb_ 

short; 

/* 

no. 

pkt-2-short since p.u 

*/ 

long 

esb_ 

long; 

/* 

no. 

pkt-2-long err since p.u. 

*/ 

long 

esb_ 

coll; 

/* 

no. 

collisions since p.u. 

*/ 

short 

esb 

MaxSize; 

/* 

maximum size packet 

*/ 

short 

esb_ 

MinSize; 

/* 

minimum size packet 

*/ 

long 

esb 

"Then; 

/* 

last 

time reading (not impl) 

*/ 

long 

esb_ 

LastTic; 

/* 

clock value at last tic 





* 

increment (not implemented) 

*/ 

long 

esb 

ticsz; 

/* 

size 

of a tic 

*/ 
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long 

esb_tind; 

/* 

index array esb_tic (wraps 





around) (not implemented) 

*/ 

long 

esb_tic[MAXTIC]; 

/* pkts per tic (n.impl.) 

*/ 

long 

esb size[MAXSZ]; 

/* hist of pkt sizes (n.i.) 

*/ 

long 

esb rtry[MAXRETRY]; /* "" no. of retries 

*/ 

long 

esb ipa[MAXGAPS] 

; /* "" intrpkt arrvls(n.i.) 

*/ 

short 

esb_ipat; 

/* 

interpkt arrival bin size 

*/ 

short 

esb_bytpkt; 

/* 

byte-per-packet bin size 

*/ 

short 

esb_retry; 

/* 

max retry value 

*/ 

short 

esb opmode; 

/* 

control to ETI 

*/ 

Command 

1 Block List 





The Command Block List (CBL) is a singly-linked list of command 
blocks awaiting execution by the ESB CPU. The header for the list 

Unit 


is 

in the 

SCB. 

When 

the 

Receive Unit is quiet. 

the 

Command 

is 

execut 

ing 

commands 

f rom 

the CBL, or wait 

ing 

for a Cha 

Attention. 

The 

"C" structure of 

a command block 

is 

as follows 

#define CB 

struct cb 

/* 

defini 

tion of cmd block 


*/ 

CB 

{ 









short 

cb 

stat; 

/* 

command block status 







* 

bit 

meaning 







* 

15-8 

unused 







* 

7 

currently execut 

ing 






* 

6 

completed execut 

ion 






* 

5,4 

reserved 







* 

3-0 

status: 







* 


0 no error (TU 

, RU) 





* 


1 invalid cmd 

(TU 

only) 


short cb cmd; 


*/ 

/* 


command 
bi t 


MAX_RETRY reached 
(TU only) 

transmit too long 
(TU only) 


meaning 


* 

15-8 

unused 

* 

7 

last cb on CBL 

* 

6 

suspend CU at end 

* 

5 

interrupt CPU at end 

* 

4 

reserved 

* 

3-0 

command: 

* 


0 no op 

* 


1 READ HOST 

* 


2 CONFIGURE 

* 


3 MULTICAST ADDRESS 

* 


4 XMIT 

* 


5 DIAGNOSTIC 


V 
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CB *cb_link; /* offset to next cb in list */ 

union { /* structures for command-specific parameters */ 

READHOST_CB readhost; /* read host address in prom */ 

CONFIG_CB confg; /* config the network intrface */ 

MC_ADDR_CB maddr; /* rev pkts w-this m.cast addrs */ 
TRANS_CB trans; /* transmit packet */ 

DIAG_CB diag; /* diagnostic command */ 

} cb_parms; 


tdefine READHOST_CB struct readhost_cb 
READHOST_CB { 

HOSTADD h_addr; /* 48-bit station address */ 

}; 

#define CONFIG_CB struct config_cb 
CONFIG_CB { 

HOSTADD cf_addr; /* 48-bit station address */ 

}; 

#define MC_ADDR_CB struct mc_addr_cb 
MC_ADDR_CB { 

HOSTADD mc_addr; /* 48-bit multicast address */ 

}; 

tdefine TRANS_CB struct trans_cb 
TRANS_CB { 

short trans_bbhdptr; /* 

HOSTADD trans_dest; /* 

HOSTADD trans_src; /* 

short . trans_type; /* 

BD *trans_bdptr; /* 

}; 

tdefine DIAG_CB struct diag_cb 
DIAG_CB { 

int (*diag routine)(); /* ptr to diag. routine */ 

}; 


DMA-style address */ 
destination of packet */ 
source of packet */ 
blue book hdr type */ 
ptr to BD with data */ 
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2.2.3.3 Receive Packet Area 

The RPA is a linked list of Packet Descriptors (PDs) with an 
associated list of Buffer Descriptors (BD). The PDs are initially 
all linked together and empty, except that the first PD has a 
pointer to the first free BD. The BDs are also linked together. 
Before reception starts, a pointer to the Ethernet header field 
in the first PD is loaded into the first FIFO register for 
receive, and a pointer to the buffer pointed to by the first free 
BD is loaded into the second FIFO register. When reception 
begins, the Ethernet header is received into the PD, and the data 
portion is received into the buffer pointed to by the first BD. 
If there is more data than the first buffer can hold, the next BD 
in the linked list is used; the next buffer pointer is loaded 
into the FIFO register immediately after the DMA fetches the 
address/count pair, so that it can be ready for a back-to-back 
receive in which the first packet is a "runt" packet. 


2.2.3.4 Packet Descriptor 


The structure of the Packet Descriptor is customized for the FIFO 
register hardware, so that it can be loaded quickly from the 
structure. 

fdefine PD struct pd /* definition of PD */ 

PD { 


short 

pd_busy; 

/* 

0/1 busy word 


*/ 

short 

pd_bbhd; 

/* 

word ptr to blue book 

hdr 

*/ 

BD 

*pd bdptr; 

/* 

pointer to first BD 


*/ 

short 

pd_end; 

/* 

marked 1 => last free 

PD 

*/ 

PD 

*pd link; 

/* 

pointer to next PD 


*/ 

short 

pd_stat; 

/* 

status field 





* 

bit meaning 





* 

0 invalid multicast 

add r 




* 

1 ran out of buffer 

space 




* 

2 CRC error 





* 

3 alignment error 





* 

4 packet too long 





* 

5 runt packet 





* 

8-15 unused 





V 



short 

pd comp; 

/* 

reception completed 


*/ 

short 

pd length; 

/* 

total length of packet 


*/ 

HOSTADD 

pd_dest; 

/* 

destination address 


*/ 

HOSTADD 

pd src; 

/* 

source address 


*/ 

short 

pd_type; 

/* 

packet type field 


*/ 
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2.2.3.5 Buffer Descriptor 

The data structure used on the ESB to keep track of, link 
together, split in two and grow buffers is the buffer descriptor 
(BD). Some conversions and derivations must be done by the ESB 
agent before passing a packet to the ESB firmware for transmis¬ 
sion, and conversely, some fields in the buffer descriptors of 
the received packets must be initialized by the ESB agent. 

The "C" representation of the buffer descriptor data structure is 
as follows: 


typedef struct bufdesc { 
union { 


} 


struct 
struct 
struct 
struct 
} bd_uarea; 
struct bufdesc 
caddr_t 
BUFP 
short 
short 


esbuffarea bd_esb; 
siobuffarea bd_sio; 
sppbuffarea bd_spp; 
uibuffarea bd ui; 


*bd_next; 

bd_address; 
*bd_buf; 
bd_length; 
bd_flags; 


/* next BD in chain 
/* buffer address 
/* pointer to buffer header 
/* length of this segment 
/* flags on buffer descriptor 


*/ 

*/ 

V 

*/ 

*/ 


struct esbuffarea { 



short 

use; 

/* 

buffer 

in use by esb 

*/ 


short 

addr ; 

/* 

shifted 

offset into 128K 

*/ 


short 

last; 

/* 

marked 

1 => last free BD 

V 


struct bufdesc 

*next; 

/* 

ptr to 

next BD in chain 

*/ 


short 

eop; 

/* 

esb, end of packet flag 

V 

}; 

short 

count; 

/* 

count for ESB datalink rev 

*/ 


The 

ESB 

DMA uses 

a word pointer, 

which supplies 

the lowest 

address 

line as 

zero, and the highest 

address line 

as a one, 

so 

the 

address of the 

data must be shifted 

right and truncated to 

16 

bi ts 

to 

feed the DMA. 






bd_ 

esb.addr = 

(short) ( ( (long) 

bd_ 

address) 





A t>n 


( 
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2.2.3.6 Network Table 


The ESB agent maintains an array of data structures containing 
initialization parameters, network address, client table and 
various pointers into shared data structures (everything it needs 
to keep track of the controller). These data structures are 
called NET structures, whose "C" representation is given below, 
along with the representation of the subsidiary CLIENT structure, 
which consists of an array used to store client and type identif¬ 
iers. 


tdefine NET 

struct net 

/* 

one structure per network 

*/ 

NET { 

INTID 

net ident; 

/* 

put on stack for handler 

*/ 

SCB 

*net scbptr; 

/* 

ptr to shared SCB structure 

*/ 

CB 

*net cblast; 

/* 

last formatted 

*/ 

CB 

*net cbnext; 

/* 

next to be recycled 

*/ 

PD 

*net_pdlast; 

/* 

last to be processed 

*/ 

PD 

*net pdnext; 

/* 

next to be processed 

*/ 

BD 

*net bdlast; 

/* 

last free 

*/ 

CLIENT 

*net clients; 

/* 

array of (client,type) 

*/ 

short 

net NextClient; 

/* 

index into client block 

*/ 

HOSTADD 

net hostadd; 

/* 

station address 

*/ 

short 

net vec; 

/* 

68000 vector number 

*/ 

long 

net offset; 

/* 

addr offset for this network 

*/ 

short 

net_opmode; 

/* 

receive mode 

*/ 

short 

net cbs; 

/* 

number of CBs 

*/ 

short 

net_pds; 

/* 

number of PDs 

*/ 

short 

net bds; 

/* 

number of BDs 

*/ 

short 

net tic; 

/* 

size of basic tic 

*/ 

short 

net max; 

/* 

size of maximum packet 

*/ 

short 

net min; 

/* 

size of minimum packet 

*/ 

short 

net_ipg; 

/* 

size of interpkt arrival bin 

*/ 

short 

net bpp; 

/* 

size of byte per packet bin 

*/ 

short 

net rtry; 

/* 

maximum retry count 

*/ 

short 

net bdcount; 

/* 

current count of buffers 

*/ 

short 

}; 

tdefine CLIE 

net EsbCmd; 

/* 

private copy of acks 

*/ 

NT struct client 

/* 

array of (client,type) 

*/ 

CLIENT { 

MBID 

client name; 

/* 

client mailbox for packets 

*/ 

short 

1 

client_type; 

/* 

this client type 

*/ 


i 


09-0018-00 


Bridge Communications, Inc 


Page 2-15 





Volume Three 


ESPL Software Technical Reference Manual 


2.3 Client Interface to ESB Agent 

Communication between the ESB Agent and its client consists of 
two procedure calls and two IPC messages, described in the fol¬ 
lowing subsections. 


2.3.1 The Eainit Procedure Call 

The eainit procedure call must be used by all clients of the ESB 
Agent The first time it is issued, the data structures are allo¬ 
cated and initialized, and the first Channel Attention is sent to 
the firmware. Also, on the first and any subsequent calls to this 
routine, the client-type data is entered in a table. Any 
received packet of the same specified type will be sent to the 
corresponding client mailbox. 

If the ESB being initialized by this call is the first ESB to be 
initialized, the ESB's host ID PROM is also read and that address 
used as the station address. If another ESB is subsequently ini¬ 
tialized, its host ID PROM will not be read. 

"C" Declaration: 

eainit ( ident, client, type, ret_parm ) 

INTID ident; 

MBID client; 

short type; 
long ret_parm; 

Input Parameters: 


ident 

client 

type 

ret_parm 


Identifies this attached network. 

Mailbox to which to send received 

All packets of this data link type 

This value is passed to the level 
the ML0RCV message as the paramete 


packets. 

go to client. 

1 client with 
r "earcv ident". 


Output Parameters: None 


Error Codes: 


NoError No error detected. 

Error Not enough memory, or invalid interrupt ID. 
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2.3.2 The EaU2Nxmit Procedure Call 


The eaU2Nxmit procedure call is used by clients of the ESB Agent 
to instruct the Agent to transmit a packet. Assuming the parame¬ 
ter "ident" is valid and there is a free command block in the 
CBL, the Agent will build a header in the command block using the 
values specified by the "dest", "src", and "type" parameters in 
the message, format a transmit command block for the ESB 
firmware, and issue a Channel Attention to the firmware. 

If the destination host is this host, the ESB agent will not send 
the message out over the Ethernet, but will instead send a mes¬ 
sage to the proper recipient within the local node. 

"C" Declaration: 


short eaU2Nxmit (m) 

Input Parameters: 

m Pointer to message (message type EA_XMITPKT). 


The message pointed to by "m" has the format: 
EA XMITMSG { 


MSG 

eaxmit sysmsg; 


INTID 

eaxmit ident; 


HOSTADD 

eaxmit eadest; 


HOSTADD 

eaxmit easrc; 


short 

} ; 

eaxmit eatype; 


Message Parameters 

• 


eaxmit_sysmsg 

System portion of message (includes 

BD) . 

eaxmit_ident 

Distinguishes between networks in a 

bridge. 

eaxmit eadest 

Destination address. 


eaxmit_easrc 

Source address. 


eaxmit eatype 

Protocol type. 



Output Parameters: Error code 
Error Codes: 


NoError 

Error 


No error detected. 

No command block available, or invalid ident. 
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2.3.3 The ML0RCV Message 

If a packet has been received when the ESB firmware issues an 
interrupt to the agent, the interrupt routine will format an 
ML0RCV message and send it to the appropriate recipient. The 
appropriate recipient is either a process which called the eainit 
procedure call with a type parameter matching this packet's type 
field, or DLNM if the packet is unclaimed. Any buffer that was 
consumed by the received packet is replaced with a new one at 
this time, and the replacement is linked to the end of the BD 
list. The PD with the Ethernet header will be recycled. 

"C" Declaration: 

ML0RCV { 


MSG 

earcv sysmsg; 

long 

earcv_ident; 

HOSTADD 

earcv eadest; 

HOSTADD 

earcv easrc; 

short 

earcv eatype; 


Message Parameters: 
earcv_sysmsg 

System portion of message (message type ML0RCV). 
earcv_ident 

Distinguishes between networks in a bridge. 
Derived from the eainit procedure call 
parameter"ret_parm". 

earcv_eadest 

Destination address. 

earcv_easrc 

Source address. 


earcv_eatype 

Protocol type. 


2.3.4 The Receiver Restart Message 

When the Receive Unit detects a resource error, it shuts down in 
a graceful manner and must be restarted by a higher level process 
after the higher-level process has unloaded the full buffers by 
shipping them off to their appropriate destinations. The agent 
interrupt service routine makes the initial steps to start the 
receiver back up by recycling used packet descriptors and replen¬ 
ishing used buffers. Some recoveries are simple, while other 
recoveries are more complex. For instance, if the last buffer is 
used, a new "last" buffer must be allocated to prime the list. 
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There are four fields in the PD and one field in the BD which 
determine the restart algorithm. The four PD fields pertain to 
the PD following the last complete packet. The four fields are 
pd_busy, pd_comp, pd_bdptr, and pd_last. The BD field is 
bd_lastfree. Table 2-1 represents a simple boolean table which 
sorts the various scenarios into a small number of cases. 

The bd_lastfree field doubles this table and is sampled on the 
last BD that is used; if bd_lastfree is TRUE, then a new BD must 
be allocated to start the new chain of free buffers. 

The agent first appraises the situation, then sets the pointers 
correctly, clears fields in partially used PDs and BDs, and sends 
a message to the higher level process. The higher level process 
checks the count of BDs on the list, replenishes it if necessary, 
and sends a control command (RU_RESUME) to the ESB firmware to 
resume the Receive Unit. The message type for the message is 
EA HELP. 


Table 2-1 Receiver Restart Algorithm 


pd_busy 


pd bdptr 

pd_comp 

pd_last 

1 FALSE 

1 

XXXX 

1 

xxxx | 

xxxx | 

| TRUE 

1 

NULL 

1 

xxxx | 

xxxx | 

| TRUE 

1 

bdptr 

1 

FALSE | 

xxxx | 

I TRUE 

1 

bdptr 

1 

TRUE | 

TRUE | 

Note: xxxx 

= don't care. 




2.4 Peer Protocol 


The Data Link Service is compatible with the data link 
described in the Ethernet Specification, Version 1.0 
[•4]) . 


protocol 

reference 
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3.0 SERIAL I/O MODULE 


This section describes the Serial I/O (SIO) Module, which pro¬ 
vides communication between an agent process and other processes 
running on the MCPU, and communication between the agent process 
and the firmware on the SIO board. 


3.1 Overview 

The Serial I/O Module is a front-end processor board which pro¬ 
vides eight RS-232-C/RS-423 full duplex lines for connecting 
serial devices to a CS/1. Each line can be independently config¬ 
ured for the type of serial device attached. 

The purpose of the SIO board is to alleviate the burden of char¬ 
acter interrupt handling in the MCPU, so that the MCPU can be 
devoted mostly to high-level protocol-processing tasks. Instead 
of interrupting on each character, the MCPU is interrupted on a 
buffer of characters. On output, when a buffer of characters has 
been transmitted, an interrupt is generated to the MCPU. On 
input, the particular conditions which cause the interrupt to the 
MCPU depend on the line discipline. 

In addition to the basic read and write commands, the SIO board 
responds to commands for setting the parameters of a line, dynam¬ 
ically changing these parameters, and flow-controlling the line. 

The following subsections describe the SIO software and its 
interfaces in detail. 


3.1.1 SIO Software 


The SIO software is comprised of firmware residing on the SIO 
board and an SIO agent (SA) which resides on the MCPU and commun¬ 
icates with the SIO firmware on behalf of the agent's client, 
normally the Virtual Terminal Process. 

The firmware maintains character flow over eight serial lines in 
a manner which is fair to all lines. It receives requests from 
the SA, and reports completion of requested actions as well as 
exceptions to the agent. The agent maintains shared data struc¬ 
tures used for communication and control between firmware and 
agent, allocates memory, and acts as an interface to the SIO's 
client processes. The agent is capable of interfacing to SIO 
firmware on up to four SIO boards; demultiplexing is based on 
port numbers, which are mapped to physical board and line numbers 
as described in Table 3-1. 
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3.1.2 SIO Hardware 

The SIO board is described in detail in reference [2]. Note that 
the SIO firmware and agent described in this manual do not util¬ 
ize all the configuration features supported by the SIO board. 
These modules' current scope is limited to asynchronous device 
support, including terminals, host computers and modems. 

The first 32 SIO ports, beginning with 0, are mapped to physical 
SIO lines as indicated in Table 3-1. 


■ 


Table 3-1 


Port No. 


SIO Line Number/Port Mapping 


SIO Board No. Line Number 


0 1 

1 1 

2 1 

3 1 

4 1 

5 1 

6 1 

7 1 

8 2 

9 2 

10 2 

11 2 

12 2 

13 2 

14 2 

15 2 

16 3 

17 3 

18 3 

19 3 

20 3 

21 3 

22 3 

23 3 

24 4 

25 4 

26 4 

27 4 

28 4 

29 4 

30 4 

31 4 


0 

1 

2 

3 

4 

5 

6 
7 
0 
1 
2 

3 

4 

5 

6 
7 
0 
1 
2 

3 

4 

5 

6 
7 
0 
1 
2 

3 

4 

5 

6 
7 
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3.1.3 Agent/Firmware Control Structure 


The firmware is initially set up with an SIO Control Block 
(SIOCB), a Command Block List (CBL), and a Character Receive Area 
(CRA). The CRA receives characters into a supply of buffers whose 
BDs are singly linked in chains. The SIOCB contains pointers to 
one LINE structure for each port; each LINE structure points to 
the first BD in a chain. The CBL is a circular list of singly- 
linked Command Blocks (CBs). 

When a buffer is completed with a termination condition commen¬ 
surate with the particular line discipline, the termination con¬ 
dition is noted in the structure associated with the buffer (BD) 
and the event is marked in the SIO's private copy of the status 
for that line. When a command from the CBL is completed, the com¬ 
pletion status is noted in the CB and likewise marked in the 
SIO's private copy of the status. 

If the MCPU has acknowledged all previous events from the SIO 
board (any of the lines may report concurrently), then the 
firmware can report a new event to the MCPU by copying the status 
and associated count fields to the SIOCB in shared memory, and 
issuing a Multibus interrupt to the MCPU. This invokes the SIO 
agent (SA), which reports these events to the appropriate client 
and restocks the CRA. 

If a BREAK condition is detected, the current read is completed 
and the status BREAK is noted in the BD associated with the 
buffer. The same is true of a change in the carrier sense or a 
receive error condition. 

The SIO Agent (SA), residing on the MCPU board, initializes the 
shared data structures for the firmware by setting up the two 
list structures used for character handling (the CRA and the CBL) 
and linking them to the SIOCB. The agent then writes the address 
of the SIOCB in a prearranged location in shared memory (the 
range 11FF00 through 11FF0F) for the SIO firmware to read, and 
issues a Channel Attention to the SIO board (the GO signal). 

Upon request of its client (usually VT), the agent formats 
request blocks for the SIO firmware using a CB in the CBL, and 
interrupts the firmware via a Channel Attention. 

The interrupt-driven portion of the SA handles completed requests 
from the SIO firmware. If a write request is completed, the agent 
frees the buffer. For a completed read buffer, the agent sends a 
message to the appropriate client process and restocks the CRA. 
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3.1.4 Initialization 

The first code that executes on both the SIO board and the MCPU 
is a multiprocessor power up diagnostic. In addition to memory 
and devices, the diagnostic tests mutual interrupt capability 
between the two processors, and in doing so determines both the 
presence of each SIO board and the firmware type assigned to the 
higher level code controlling the board. This information is 
stored on the MCPU in a globally accessible structure. If an OEM 
customer replaces the higher level code of the SIO firmware and 
develops a new agent to run with some or all of the existing ESPL 
software, a different type code must be assigned to the new 
firmware. 


** NOTE ** 

Firmware type codes are two-byte codes allocated by 
Bridge Communications to uniquely identify each dif¬ 
ferent set of higher-level code controlling an SIO 
board. To obtain a new firmware type code, contact 
Document Control, Bridge Communications, Inc., 10440 
Bubb Road, Cupertino, CA 95014. 

Additionally, the OEM firmware and agent must not use the 
addresses in the range 11FF00 to 11FF0F for the equivalent of the 
SIOCB pointer. Instead, the addresses from 11FEF0 to 11FEFF 
should be used as an array of four pointers to the shared struc¬ 
ture . 

The SIO firmware initializes its own private structures, then 
waits for the first Channel Attention from the SIO agent. 

For each SIO board, the agent allocates all the shared data 
structures (CBL, CRA, and SIOCB), writes the address of the SIOCB 
in a known location, then sends the first Channel Attention to 
the SIO firmware. 

3.1.5 Line Configuration 

Upon client request (e.g., VT) , the agent allocates memory in 
shared memory, copies the relevant parameters from the UI parame¬ 
ters into the shared memory block, gets the first free CB in the 
CBL for the SIO line, fills in the command field and parameter 
field (pointer to the shared memory with the parameters), and 
issues the Channel Attention to the SIO board. 

The SIO firmware interprets the command on the CBL and copies the 
relevant parts into the Line Control Block (LCB) for that line. 
Then the UART is initialized according to the parameters that 
control the physical device. The SIO line is now ready for 
operation. 
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3.1.6 Transmission 


The client requests transmission by specifying the SIO line 
number and the buffer descriptor with the data. 

The agent gets the pointer to the first free CB in the CBL of the 
SIO line, and fills in the fields. 

The agent uses the control command field in the SIOCB to inform 
the SIO firmware of the presence of a CB on the list and issues a 
Channel Attention to the SIO board to draw its attention to the 
command. The SIO firmware is now responsible for the transmis¬ 
sion . 


3.1.7 Reception 

The agent sets the firmware up with a list of BDs in which to 
receive characters before the UARTs are even initialized. 

The interrupt service portion of the agent receives the Multibus 
interrupt from the SIO firmware and notes that a read has been 
completed. The agent sends the buffer to the appropriate data 
mailbox. 


3.2 Communication Between Firmware and Agent 

The MCPU and the SIO are loosely coupled processors, each with a 
private memory space, I/O space and Multibus mastership capabil¬ 
ity. They exchange information in shared data structures con¬ 
tained in ESB memory. The control mechanisms that govern the 
exchange consist of a mutual hardware interrupt capability, 
software control flags and commands. This section describes these 
mechanisms and the way they are used to achieve processor syn¬ 
chronization . 


3.2.1 Channel Attention 

The Channel Attention interrupt is used by the SA to interrupt 
the SIO firmware in order to pass a new command (or set of com¬ 
mands) or to acknowledge receipt of a command completion notice. 
The Channel Attention is a decoded address interrupt and does not 
consume a Multibus interrupt level. It is automatically cleared 
by the SIO board in hardware. There is one Channel Attention 
interrupt per SIO board. The SA generates a Channel Attention by 
writing to the locations indicated in Table 3-2. 
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3.2.2 Multibus Interrupt 

The Multibus interrupt is used by the SIO firmware to interrupt 
the SA upon completion of a command (or set of commands). As its 
name indicates, it is a real Multibus interrupt. It is cleared by 
the SIO agent on the MCPU. There is one Multibus interrupt for 
all SIO boards, and one Multibus interrupt clear address for each 
SIO board (see Table 3-2). 


3.2.3 SIO Reset 

The SIO board can be reset by the MCPU. Once reset, the board is 
held in reset mode until a reset clear is received. The 
addresses written to for reset and reset clear are listed in 
Table 3-2. 


Table 3-2 SIO Channel Attention, Multibus 
Interrupt and Reset Addresses 



SIO 1 

SIO 2 

SIO 3 

SIO 4 

Function 

Address 

Address 

Address 

Address 

Channel 

1E0000 

1E8000 

1F0000 

1F8000 

Attention 





Multibus 

E00000 

E00000 

E00000 

E00000 

Interrupt * 





Multibus 

1E2000 

1EA000 

1F2000 

1FA000 

Interrupt Clear 





Reset 

1E4000 

1EC000 

1F4000 

1FC000 

Reset Clear 

1E6000 

1EE000 

1F6000 

1FE000 

* The same 

address is 

used by all 

boards; 



SIO jumper E61 indicates which of eight Multibus 
interrupts will be generated (see reference [2] 
for jumper information). 
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3.2.4 Software Control Flags 

The SIO firmware maintains two software flags for synchroniza¬ 
tion. The flag "rev" indicates how many lines have a control 
command outstanding, while the flag "sent" indicates whether or 
not the SIO firmware is expecting an acknowledgment from the 
MCPU. Both flags are read and written by the SIO firmware only. 
Together with a few rules, they determine how the two processors 
become synchronized and achieve mutual exclusion of access to 
shared data structures. 

The "rev" flag is zero when the SIO firmware is in its initial 
state, and is incremented in the Channel Attention interrupt ser¬ 
vice routine when the MCPU issues a control command to the SIO 
firmware. The flag value is decremented at the time a control 
command is interpreted and acted upon. 

The "sent" software control flag value is false when the SIO 
firmware is in its initial state, and is set to true immediately 
after a Multibus interrupt (command completion notification) has 
been issued to the MCPU. It is set to false in the Channel Atten¬ 
tion interrupt service routine when the MCPU issues an ack¬ 
nowledgement to the SIO CPU. 


3.2.5 Commands 


There are two types of commands to which the SIO firmware 
responds: control commands (resume, suspend, acknowledgements, 
and send break) and block commands (set parameters, transmit, 
change a parameter, and send break). The SIO firmware reports 
asynchronous events to the SIO agent on the MCPU via status 
fields in the LINE structure and the interrupt line. 

Control commands are communicated to the SIO firmware via the 
LINE structure, and have no parameters. The MCPU writes the com¬ 
mand into the command field in the LINE structure and issues a 
channel attention to the SIO CPU. The SIO CPU acknowledges com¬ 
pletion of any of these commands by writing a zero into the same 
command field and clearing the Channel Attention. 

Block commands (set parameters, transmit, change a parameter, 
send break) are received by the agent from the client in a mes¬ 
sage passed to one of the agent's procedures. The agent formats 
them into a CB and chains them into the CBL for the particular 
line on the particular SIO board. A channel attention is then 
issued with the control command "resume the Command Unit”. 
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3.2.6 Synchronization 

The following rules must be observed to achieve synchronization: 

1. The Agent must wait for the command fields in the LINE 

structure to be reset by the SIO firmware before setting 

them again to issue a control command. 

2. The Agent must write the command field into the LINE struc¬ 

ture before issuing a Channel Attention interrupt. 

3. While Sent is true, the SIO firmware cannot modify the 

status fields of the LINE structure. 

4. The Sent and Rev flags should change state after the 

occurrence of the event rather than before. 

The steps necessary to achieve synchronization are illustrated in 

Figure 3-1. 


Agent 


Wait for command fields 
to be cleared 
Format LINE structure 
Channel Attention ===> 


New commands and Channel 
Attention allowed 


Clear Multibus Interrupt 
Read LINE structure status 
Issue acknowledgement 
Channel Attention ===> 


Firmware 

Initial State 
Rev = 0 
Sent= F 


Rev —> +=1 
Sent= F 

Rev --> -=1 

Clear command fields 


<=== Multibus Interrupt 
Sent —> T 


Sent —> F 

Clear acknowledgement 
If cmd pending. 

Rev —> +=1 


Figure 3-1 Synchronization Control 
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3.2.7 Data Structures 


The SIO agent and firmware use ESB shared memory for the SIOCB, 
the CBL and the CRA. The following subsections describe these 
shared data structures. Also described are the data structures 
CS and SIOPORT, which are kept by the agent in private memory and 
are used to store information on a per-board and per-line basis. 
These data structures are included here because they contain 
pointers into the CBL and CRA that reflect current CB and buffer 
utilization. 

The data structures used by the SIO firmware and agent are illus¬ 
trated in Figure 3-2. 
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+ - + - +-+-+ 

ISI01nit_ptr Array (11FF00) 

I [1] | [2] | [3] | [4] 

4-1-f--H-H-+-1-4--4* 

I v I I 

v v r> 

H-— — + —-(- V 



+ --+ - + - +-+ - + - + - + - + 


[1] | [2] | [3] | 

[4] 

CSTable Array 



+ - + - + - + - + 


Figure 3-2 SIO Data Structures 
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3.2.7.1 SIO Control Block 

The SIOCB is a shared data structure containing the fields for 
interprocessor communication. There are eight 

sources/destinations for characters, so the body of the structure 
is an array structure; but there is an overall structure for the 
entire board which facilitates the search for the interrupting 
line, and enables information about several lines to be exchanged 
in one interrupt. There is a LINE structure for each of the 
eight ports, containing pointers to the CRA and the CBL as well 
as fields for error and statistic information. 

The SIOCB and LINE structures have the following format: 

#define SIOCB struct siocb 

SIOCB { 

short sio_statmask; /* bit mask - Each line is 

assigned a bit. The assigned 
bit is ON if the interrupt 
to the MCPU has information 
from that line. The obvious 
bit assignment is made, i.e. 
bit #n is used for line #n. 

*/ 

short sio_cmdmask; /* bit mask - The assigned 

bit is ON if the channel 
attention from the MCPU has 
information for that line, 
acknowledgement or new cmd. 
Again, the obvious bit 
assignment has been made. 

*/ 

LINE *sio_lines[8]; /* pointers to the structures 

of the individual lines. A 
pointer is picked from here 
when it is determined (by 
checking the masks) which line 
has new information. 
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tdefine LINE struct line 
LINE { 

short line_stat; /* 

bit meaning 

8- 15 unused 

7 command (s) completed 

6 read(s) completed 

5 CU gone not ready 

4 RU gone not ready 

3 CU ready/not ready 

2 RU ready/not ready 

1-0 unused 

*/ 

short line_cmd; /* 

bit meaning 

9- 15 unused 

8 out of band break 

7 ack command complete 

6 ack read complete 

5 ack CU not ready 

4 ack RU not ready 

3 suspend CU 

2 resume CU 

1 suspend RU 

0 resume RU 

*/ 


BD 

*line_cra; 

/* 

ptr 

to 

char rev 

area 

*/ 

CB 

*line_cbl; 

/* 

ptr 

to 

first CB 


*/ 

short 

line_cmdcmplt; 

/* 

cnt 

of 

complete 

CBs 

*/ 

short 

line_readcmplt ; 

/* 

cnt 

of 

complete 

reads 

*/ 

short 

line parityerr; 

/* 

count 

of parity 

errors 

*/ 

short 

line bderr; 

/* 

count 

of characters lost 



* 

due 

to 

lack of 

buffers 

*/ 


G 
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3.2.7.2 Command Block 

The SIO Command Block (SIOCB) is a shared data structure. A com¬ 
mand (e.g., initialize, write or change parameter) is given to 
the SIO firmware by chaining it into the Command Block List 
(CBL). The CBL is a circular, singly-linked list of blocks, the 
last of which is marked by the absence of a command in the com¬ 
mand type field. Each line has its own CBL, and keeps a pointer 
to the beginning of the CBL in the SIOCB. 

#define CB struct cb 

CB { 

short cb_stat; 
short cb_cmd; 

CB *cb_link; 

union { 

SI0_INIT 
SIO_WRITE 
S10_CHG PARM 
SIO_CONNECT 
SI0_DISCONNECT 
SIO_DIAG 
} cb parms; 

}; 

SI0_INIT { 

UIBLK *i_ptr; 

} ; 

SIO_WRITE { 

BD *w_ptr; 

short w_eom; 

} ; 

SI0_CHGPARM { 

short chg_parmno; 

short chg parmval; 

}; 

SI0_C0NNECT { 

BD *c_bufdes; 

char *c_ptr; 

short c_len; 

}; 

SI0_DISCONNECT { 

}; 

SI0_DIAG { 

int (*diag_routine) () ; 

}; 


sio_init; 
sio_write; 
sio_chgparm; 
sio_connect; 
sio_disconnect; 
sio_diag; 
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3.2.7.3 SIO Agent Private Data Structures 

The private structures CS and SIOPORT are used by the agent and 
network management. These structures contain configuration vari¬ 
ables, pointers for tracking the lists of CBs and buffers, and 
line or board identification such as interrupt identifiers. 


#define CS 

struct cs 

/* 

per-board structu 

re 

*/ 

CS { 

INTID 

cs ident; 

/* 

interrupt id for 

board 

*/ 

SIOCB 

*cs_siocbptr; 

/* 

ptr to SIOCB for 

this board 

*/ 

short 

cs vec; 

/* 

vector offset 


*/ 

SIOPORT 

}; 

*cs_lines[8] ; 

/* 

individual lines 


*/ 


Idefine SIOPORT struct sioport /* per-line structure */ 


SIOPORT { 
short 

siop_index; 

/* 

index in table 

*/ 

short 

siop_state; 

/* 

connected or not 

*/ 

MSG 

*siop_safull; 

/* 

msg kept when mbox full 

*/ 

MBID 

siop_cmbox; 

/* 

client control mailbox 

*/ 

MBID 

siop_dmbox; 

/* 

client data mailbox 

*/ 

CB 

*siop cblast; 

/* 

first free CB 

*/ 

CB 

*siop_cbnext; 

/* 

next CB to process 

*/ 

BD 

*siop_bdnext; 

/* 

next BD to process 

*/ 

BD 

*siop_bdlast; 

/* 

last BD in receive area 

*/ 

short 

siop_qcount; 

/* 

no. of unused buffers 

*/ 

short 

siop cbs; 

/* 

number of CBs per line 

*/ 

short 

siop bds; 

/* 

number of BDs per line 

*/ 

short 

siop_bdcount; 

/* 

no. of buffers in chain 

*/ 

short 

siop bdsz; 

/* 

size of buffer 

*/ 


}; 
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3.3 Client Interface to SIO Agent 

The agent receives requests in the form of procedure calls 
directed to a specific line number and gives notification in the 
form of IPC messages to the client's control mailbox. The pro¬ 
cedure calls all take message pointers as parameters. Since the 
BD parameter is already in the message, the message block can 
easily be reused, thus reducing overhead. 

The SA keeps track of the connection state of each line. The 
state of being connected or disconnected is associated with the 
establishment of a Virtual Terminal process for an SIO line. When 
the SA receives any data while in the disconnected state, it 
sends a connect request message to the Parent Virtual Terminal 
process. Once a VT process is established, it notifies the SA of 
data and control mailboxes to which to send messages. 

For the IPC portion of the interface, the agent uses a standard 
message header (SAMSG) which has a standard data structure as 
follows: 

SAMSG { 

MSG sa_msg; /* the system message */ 

ushort sa_portid; /* the SIO line number */ 

}; 


3.3.1 Connect Request Procedure Call and Message 

The connect request procedure call is issued by a VT process to 
connect itself to an SIO line. The connect request message is 
sent by SA to the Parent VT to request the establishment of a VT 
process for an SIO line. The message has the same format as that 
passed as a parameter in the procedure call. A connection 
request may be rejected by sending a disconnected message back to 
the requestor. 

Procedure Call "C" Declaration: 

saV2Sconnect (m) 

MSG *m; 

Input Parameters: 

m Message pointer. 
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The format of the connect request message (whether pointed to by 
"m" in the procedure call or sent as an IPC message) is as fol¬ 
lows : 

SACONNECT { 

SAMSG sacjmsg; 

MBID sac_cmbox; 

MBID sac_dmbox; 

}; 

The parameter "sac_msg" has the standard SAMSG format, and con¬ 
tains the system message, a line number and a message type of 
MSACONN. When passed as a parameter in a procedure call, the 
other parameters of the message block indicate the control mail¬ 
box and data mailbox of the requesting VT process. 


3.3.2 Disconnect Request Procedure Call and Message 

The disconnect request procedure call is issued by a VT process 
to disconnect itself from an SIO line. The disconnect request 
message is sent by SA to a VT process to request disconnection 
from an SIO line. Disconnection invalidates the VT data and con¬ 
trol mailboxes, so that any further data from the line causes a 
connect request message to be sent to the Parent VT process. 
Disconnection also flushes input and output, and drops DCD to the 
device if the UseDCDout parameter is set to "OnConnection". 

Procedure Call "C" Declaration: 

saV2Sdisconnect (m) 

MSG *m; 

Input Parameters: 

m Message pointer. 

The format of the disconnect request message is as follows: 

SADISCONNECT { 

SAMSG sad_msg; 

ushort sad_reason; 

}; 


The parameter "sad_msg" has the standard SAMSG format, with a 
message type of MSADISCONNECT. The "sad_reason" parameter values 
are passed to SA by VT and are defined in Section 5.3.9. 
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3.3.3 Connected Procedure Call 

The connected procedure call is issued by a VT process to SA in 
order to inform SA of the establishment of a connection. 

Procedure Call "C" Declaration: 

saV2Scnctd (m) 

MSG *m; 

Input Parameter: Message pointer 

The format of the connected message is as follows: 

SACNCTD { 

SAMSG 
MBID 
MBID 

>; 

The parameter "sacd_msg" has the standard SAMSG message block 
format, with a message type of MSACNCTD. The other parameters 
are the VT command and data mailboxes. 

3.3.4 Disconnected Procedure Call and Message 

The disconnected procedure call is issued by VT to SA to ter¬ 
minate a connection (e.g., when VT wishes to notify SA that a 
connection has been terminated at the remote end). The discon¬ 
nected message is sent by SA to VT to terminate a connection 
(e.g., when SA wishes to advise VT that carrier is lost on an SIO 
line) . 

Procedure Call "C" Declaration: 

saV2Sdscnctd (m) 

MSG *m; 

Input Parameter: Message pointer 

The format of the disconnected message is as follows: 

SADSCNCTD { 

SAMSG sadd_msg; 

ushort sadd_reason; }; 

The parameter "sadd_msg" has the standard SAMSG format, with a 

message type of MSADSCNCTD. The "sadd_reason" parameter values 
are passed to SA by VT and are defined in Section 5.3.9. 


sacd_msg; 
sacd_cmbox; 
sacd dmbox; 
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3.3.5 Board Initialization Procedure Call 


This procedure call is issued by the Parent Virtual 
cess once per SIO board at initialization time to 
to initialize the SIOCB, CRA and CBL for each line 
according to the initial configuration state 


Terminal pro¬ 
request the SA 
of the board 
(which may say 


DO NOT INITIALIZE). 


Procedure Call "C" Declaration: 


salnitCBlck (board); 


3.3.6 


Set Parameters Procedure Call 


The client (e.g., VT) issues this procedure call on a per-line 
basis to specify the parameters of the SIO line according to the 
set negotiated between the user interface and the user, or in 
response to a Rmtset command. All the parameters are affected, 
and the SIO line is initialized. 


Procedure Call "C" Declaration: 

saV2Ssparm (m) 

MSG *m; 

Input Parameters: Message pointer 

Output Parameter: Error code 

Error Codes: 


The 


NoError 

Error 

SAFULL 


No 

error detected 

(0) • 

No 

memory 

blocks 

available 

te 

rs (-1). 



No 

command 

block 

available 


for a copy of parame- 
for requested operation 


(1) . 


message block pointed 


to by "m" has the following format: 


SASPARM { 

SAMSG sas_msg; 

UIBLK *sas_parmset; 

}; 


The parameter "sas_msg" has the standard SAMSG format, and con¬ 
tains a line number and a message type of MSASPARM. The parame¬ 
ter "sas_parmset" points to the block of UI parameters which 
determine the specified line's parameters. 
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3.3.7 Change Parameter Procedure Call 

This procedure call is used to change a single parameter in the 
parameter list. 

Procedure Call "C" Declaration: 

saV2Schgp (m) 

MSG *m; 

Input Parameters: Message pointer 

Output Parameter: Error code 

Error Codes: 

NoError No error detected (0). 

SAFULL No command block available for requested operation 
(1) • 

The SIO line, the parameter number and the new value are parame¬ 
ters in the message block, which has the format: 

SACHGP { 

SAMSG sach_msg; 

ushort sach_parmno; 

ushort sach value; 

}; 

The parameter "sach_msg" has the standard SAMSG format, with a 
message type of MSACHGP. 
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3.3.8 Flow Control Procedure Call 

When SA cannot send received data to VT because VT's data mailbox 
is full, SA changes the message type to MSAFLCTRL and sends the 
message to VT's control mailbox instead. When VT receives this 
message, it passes the message as a parameter to the procedure 
call saV2Sflctrl, which again attempts to forward the data to 
VT's data mailbox. The cycle repeats if the data mailbox is 
full. 

Procedure Call "C" Declaration: 

saV2Sflctrl(m) 

MSG *m; 

Input Parameter: 

m Message pointer. 

The message block pointed to by "m" has the format: 

SAFLCTRL { 

SAMSG safl_msg; 
ushort safl_ctrl; 

}; 

The parameter "safl_msg" has the standard SAMSG format, with a 
message type of MSAFLCTRL. 

3.3.9 Restart Line Procedure Call and Message 

When the SIO firmware needs to flow control a line, it uses this 
message. The line may have run completely out of buffers if no 
flow control mechanism is used or if the client's data mailbox is 
full for a long time (e.g., if the remote end of the connection 
is flow-controlled). In this case, the interrupt routine sends 
an SAMSG to the Parent Virtual Terminal process, which in turn 
issues the restart line procedure call with the same message to 
initiate reception again. The cycle repeats if the line does not 
have an adequate supply of buffers. 

Procedure Call "C" Declaration: 

saV2Srestart (m) 

MSG *m; 

Input Parameter: 

m Message pointer. 

The restart message block has the standard SAMSG format, and a 
message type of MSARESTART. 
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3.3.10 Send Data Procedure Call 

This procedure call is used to transmit data to the SIO line. The 
buffer descriptor and the SIO line are passed in the message as 
parameters. The parameter "sada reason" indicates whether or not 
an EOM signal accompanies the buTfer. The EOM is mapped according 
to the parameter set for the port. If the data cannot be chained 
into the Command Unit of the SIO line, the return code indicates 
the reason. 

Procedure Call "C" Declaration: 
short 

saV2Sdata (m) 

MSG *m; 

Input Parameter: 

m Message pointer. 

Output Parameter: 

Error code 
Error Codes: 

NoError No error detected (0). 

SAFULL No command block was available (1). 

The send data message block pointed to by "m" has the format: 

SADATA { 

SAMSG 
ushort 

}; 

The parameter "sada_msg" has the standard SAMSG format, and a 
message type of MSADATA. 


sada_msg; 
sada reason; 
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3.3.11 Receive Data Message 

This message is sent from interrupt level to the client data 
mailbox when a read is completed on the line. The reason for com¬ 
pletion is passed in the message, and comes from the status field 
of the BD for the received buffer. 

"C" Declaration: 

SADATA { 

SAMSG 
ushort 

}; 

The parameter "sada_msg" has the standard SAMSG format, and a 
message type of MSADATA. 


sada_msg; 
sada reason; 


3.3.12 Send Attention Procedure Call 

The attention procedure call is called when the VT process needs 
to send a BREAK to the SIO line. The attention message is sent 
from the interrupt level of SA to the VT control mailbox when a 
BREAK is detected on the SIO line. 

Procedure Call "C" Declaration: 

saV2Sattn (m) 

MSG *m; 

Input Parameter: 

m Message pointer. 

Output Parameter: 

Error code 


Error Codes: 
NoError 
SAFULL 

The format of 


No error detected (0). 

No command block was 
operation (1). 

the attention message is 


available 

as follows: 


for 


requested 


SAATTN { 

SAMSG 

ushort 

}; 


saa_msg; 
saa_signal; 
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The parameter "saa_msg" has the standard SAMSG format, and a mes¬ 
sage type of MSAATTN. The message parameter "saa_signal" indi¬ 
cates whether the BREAK should be sent in-band or out-of-band. 
When directed to an SIO line by VT, the in-band BREAK is sent in 
a Command Block and follows any outstanding commands, while the 
out-of-band BREAK is issued as a control command and so occurs 
immediately. 


3.3.13 Full CBL Message 

Each SIO line has a small number of preallocated command blocks. 
If all of a line's command blocks are full, and a procedure call 
is received which requires a command block, the agent generates a 
return code of SAFULL and saves the pointer to the message used 
in the procedure call. When a command block becomes available, 
SA sends the saved message back to the client with a message type 
of MTMSAFULL. It is the responsibility of the client to remember 
the original message type and to reissue the procedure call. 

The procedure calls which require a command block are the send 
data procedure call, the attention procedure call, the set param¬ 
eters procedure call, and the change parameters procedure call. 
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